/*******************************************************************************
filename      Parser.h
author        Craig Williams
last modified 05-24-08
version       8.0

Description:
  Provides a parser library, as well as several string manipulation funcitons
    to allow for easy parseing of a file. The library handles all file input
    and as much clean up as possiable.

  WARNING: This library heavly uses malloc. The character array returned by
           GrabToken(), PeekToken(), and GrabBytes(<bytes>) must be freeded with
           free(<char *>); manually.

           There are no memory leaks inside the parser library.

  NOTE: Unicode is not supported.

  NOTE: Only Little Endian is supported.

  Parser Functions:
      ParserInit      - Initializer. Takes in a string that contains
                          the file to load, as well as how many bytes to read
                          in from the file at one time (Recommended: 1 KB)
      ParserDeInit    - Frees all the memory used by the parser
      LoadFile        - Opens and loads a new text file into the parser.
      LoadMemory      - Loads a chunk of memory (char *) into the parser for
                          processing. In other words, don't use internal file
                          handleing. NOTE: MEMORY IS COPPIED.
      LoadMemoryLen   - Same as above; however, it takes in the lenght of the
                          memory.
      AddTokenSet     - Adds another Token set. Allows for easy switching
                          between various parseing modes, as well as a built in
                          branching system.
      SetTokenSet     - Changes the current Token Set.
      GetTokenSet     - Returns the current Token Set.
      AddTokenSeparator - Adds a new "Token Separator" to the current token set.
                            A Token Separator is simply the string to check for
                            in the string we are parseing. Depending on the
                            flags you pass in, you can remove this token
                            from being returned from Grab/Peek Token, or do
                            some basic branching.
      AddTokenSep     - Calls the above function, with the default values.
      GrabToken       - Gets the next token from the string, and then updates
                          our position in the string.
      PeekToken       - Gets the next token from the string without updateing
                          our position in the string. All token logic, except
                          for callbacks, is taken into account.
      GrabInt         - Gets the next token from the string, and attempts to
                          convert it to a int. This function handles all
                          required cleanup.
      GrabBinaryInt   - Reads in the next sizeof(int) bytes, and returns them
      GrabFloat       - Gets the next token from the string, and attempts to
                          convert it to a float. This function handles all
                          required cleanup.
      GrabBinaryFloat - Reads in the next sizeof(float) bytes, and returns them
      GrabChar        - Reads in the next byte, and returns it.
      GrabBytes       - Reads in a specific number of bytes from the file, and
                          returns them.
      Seek            - Searches the string for the specified token, and then
                          updates our position in the string, to the character
                          directly following the token.
      SetFilePosition - Changes our location in the file, and reads in the new
                          data, from the specifed location.
      GetFilePosition - Returns the current file position.

      ErrorCode       - Returns the current error code (check defines in
                          parser_core.h).
      PrintErrorCode  - Prints out the Error Code, in a text format to the
                          command prompt.
      End             - Returns 1 if there was a error, or if we reached the end
                          of the file - No more processing possiable.
      GetParserState  - Returns a pointer to the current Parser state.
      SetParserState  - Changes the current Parser state to the specifed state

      GenericDiscard  - Supplied Parser callback, that discards the next token

  String Manipulaiton functions:
      RemoveWhiteSpaces - Removes all white spaces from a string (Space, New
                            Line, Carriage Return, and Tab)
      ToUpper     - Converts all letters in a string to upper case
      ToLower     - Converts all letters in a string to lower case
      Dup         - Creates a copy of the specfied string
      DupLen      - Same as above, but it takes in the length of the string
      DupRange    - Creates a copy of a specific part of a string
      DupRangeFile- Creates a copy of a specific part of a file
      Cmp         - Compairs two strings. If they are equal, 1 is returned. If
                      not, 0 is returned.
*******************************************************************************/
#ifndef OLD_PARSER_CORE
#define OLD_PARSER_CORE

namespace OldParser
{

  /* Parser error codes. PrintError() will automatically translate these error*
   *   codes to the command prompt.                                           */
#define PARSER_NOT_INITIALIZED       -1
#define PARSER_NO_ERROR               0
#define PARSER_COULD_NOT_OPEN_FILE    1
#define PARSER_OUT_OF_MEMORY          2
#define PARSER_END_OF_FILE            3
#define PARSER_MEMORY_NOT_VALID       4
#define PARSER_GRAB_TOKEN_IGNORE      5

typedef int (*PARSER_CALLBACK)(void *);

  /* Parser Functions */
void  ParserInit       (const char *file,
                        int   bufsize      ); /* default - 1024 (1 KB)        */
void  ParserDeInit     (void               );
int   LoadMemory       (const char *memory       );
int   LoadMemoryLen    (const char *mem,  int len);
int   LoadFile         (const char *file         );
int   AddTokenSet      (void               );
int   SetTokenSet      (int   tokenset     );
int   GetTokenSet      (void               );
int   AddTokenSeparator(const char *token,
                        char  Return,         /* default -  1 Return as token */
                        signed char  switchto,/* default - -1 Dont change Tset*/
                        char  ignore,         /* default -  0 Dont ignore     */
                        int  (*fun)(),        /* default -  0 No callback fun */
                        void  *params      ); /* default -  0 No callback parm*/
int   AddTokenSep      (const char *sp           ); /* AddTokenSeparator with defaul*/
char *GrabToken        (void               );
char *PeekToken        (void               );
int   GrabInt          (void               );
int   GrabBinaryInt    (void               );
float GrabFloat        (void               );
float GrabBinaryFloat  (void               );
char  GrabChar         (void               );
char *GrabBytes        (int   bytes        );
int   Seek             (const char *search       );
int   SetFilePosition  (long  fpos         );
long  GetFilePosition  (void               );
int   ErrorCode        (void               );
void  PrintErrorCode   (void               );
int   End              (void               );
void *GetParserState   (void               );
void  SetParserState   (void *state        );
int   ParserMemoryUsage(void               );

  /* Generic Parser Callbacks */
int   GenericDiscard   (void *             );

  /* String Minipulation Functions */
int   RemoveWhiteSpaces(char *sp                            );
void  ToUpper          (char *sp                            );
void  ToLower          (char *sp                            );
char *Dup              (const char *sp                      );
char *DupLen           (const char *sp,   int len           );
char *DupRange         (const char *sp,   int start, int end);
char *DupRangeFile     (const char *file, int start, int end);
char  Cmp              (const char *osp,  const char *osp2  );

}

#endif
